6.1 Generating and Obtaining a Software Statement Assertion (SSA)

Before using Postman, you need to generate an obtain a Software Statement Assertion (SSA) for your application, which you will use to connect to the REST APIs. You can use the following guidance to achieve this.

An SSA is a signed JWT token with information about the Application that is presented to Cloudentity when performing DCR (the last step before accessing the REST APIs).

Overview

First, generate an SSA for your application in the Thredd CA dashboard.

Once you have generated the SSA, obtain the SSA through either Postman or an API-based method for connecting to Thredd CA (as this page describes). For details of the steps in Postman, see Accessing the Cards API with mTLS.

Prerequisites

You must have completed Thredd's onboarding process, set up SSO and Cloudentity, and have an account in the Thredd CA dashboard. These steps are summarised in Setup Steps.
You must have registered your application in Thredd CA and generated Transport Certificates for it. For a guide, see Creating Client Application Certificates for REST APIs.

6.1.1 Generating an SSA in Thredd CA

You can generate an SSA for your Application under the Applications > Application Assertion section for your Organisation.

From the list of Organisations, click on the relevant tile.
Click Applications.

Select the Application that you want to generate an assertion for under Applications.
Click the Assertion tab.
Click the Generate button. A message appears followed by the Assertion.

6.1.2 Obtaining an SSA Using API Calls

You can use API calls from outside of Thredd CA in order to request the SSA, which you generated on Thredd CA. This includes the command for acquiring an access token for connecting to Thredd CA, and the command for requesting an SSA. The command for acquiring an access token executes a Client Credentials Grant, which initiates a request to Thredd CA over mTLS.

You need to have also created a Transport Certificate for accessing Thredd CA (see Creating Client Application Certificates for REST APIs for more details). You will need to prepare the Client ID and the SSA details.

Preparing the Client ID Details

You will need to get the client_id URL which includes the URL of Thredd CA and the Client ID.

The following is an example:

client_id=https://rp.directory.sandbox.threddid.com/openid_relying_party/b9f04639-cdeb-425b-a310-450d3d293fd4.

You can find the Client ID on the Organisations page in Thredd CA.

Log in to Thredd CA using these links:
- Sandbox: https://web.directory.sandbox.threddid.com/
- Production: https://web.directory.threddid.com/
In the Sign-in screen, enter your registered email address and click CloudEntity SSO.
Locate the organisation tile and copy the Client ID.

Preparing SSA Details

You need to prepare details of the SSA for the SSA URL.

The following is an example: client_id=https://rp.directory.sandbox.threddid.com/openid_relying_party/b9f04639-cdeb-425b-a310-450d3d293fd4

This includes:

{{rc_mtls_base_url}}: This is the variable for the Base URL for Thredd CA
{{org_id}}: The Organisation ID
SSA ID: This is the ID of the SSA, which is the same as the Application ID

Entering Commands to Obtain an SSA

Enter the following command for acquiring an access token. This includes the URL of the Thredd CA in location.

Copy

curl --location 'https://matls-auth.directory.sandbox.threddid.com/token' \
                --header 'Content-Type: application/x-www-form-urlencoded' \
                --data-urlencode 'scope=directory:software' \
                --data-urlencode 'client_id=https://rp.directory.sandbox.threddid.com/openid_relying_party/b9f04639-cdeb-425b-a310-450d3d293fd4' \
                --data-urlencode 'grant_type=client_credentials'

Type in the following command to request an SSA. This includes the SSA URL.

Copy

curl --location 'https://matls-auth.directory.sandbox.threddid.com//organisations/99b2b599-8cc2-499e-b805-e3d84233ae8e/softwarestatements/b9f04639-cdeb
                -425b-a310-450d3d293fd4/assertion' \
            --header 'Authorization: Bearer <access_token>'

The response you see is as follows. This includes the SSA in Base 64 format and the metadata associated with the SSA.

Copy

{
  "client_name":"Test Org 4",
  "description":"",
  "client_uri":"",
  "logo_uri":"https://example.com/logo.png",
  "policy_uri":"",
  "tos_uri":"",
  "organisation_id":"",
  "client_id":"https://rp.directory.sandbox.threddid.com/openid_relying_party/b9f04639-cdeb-425b-a310-450d3d293fd4",
  "application_type":"service",
  "application_types":[
    "service",
    "dcr"
  ],
  "redirect_uris":[
    "https://example.com/cb"
  ],
  "grant_types":[
    "client_credentials"
  ],
  "response_types":[
    "token"
  ],
  "scope":"3ds.read bulkcard.read bulkcard.write cards.encrypted cards.read cards.sensitive cards.write cvv.read cvv.write digitalchannel fraud.read fraud.write internal.read internal.write issuer.read issuer.write pin.read pin.write",
  "scopes":[
    "3ds.read",
    "bulkcard.read",
    "bulkcard.write",
    "cards.encrypted",
    "cards.read",
    "cards.sensitive",
    "cards.write",
    "cvv.read",
    "cvv.write",
    "digitalchannel",
    "fraud.read",
    "fraud.write",
    "internal.read",
    "internal.write",
    "issuer.read",
    "issuer.write",
    "pin.read",
    "pin.write"
  ],
  "audience":[
    "https://rp.directory.sandbox.threddid.com/openid_relying_party/b9f04639-cdeb-425b-a310-450d3d293fd4"
  ],
  "token_endpoint_auth_method":"private_key_jwt",
  "revocation_endpoint_auth_method":"private_key_jwt",
  "introspection_endpoint_auth_method":"private_key_jwt",
  "token_exchange":{
    "actor_claims":null
  },
  "token_endpoint_auth_signing_alg":"",
  "jwks":{
    "keys":[
      
    ]
  },
  "jwks_uri":"https://keystore.directory.sandbox.threddid.com/99b2b599-8cc2-499e-b805-e3d84233ae8e/b9f04639-cdeb-425b-a310-450d3d293fd4/application.jwks",
  "request_object_signing_alg":"RS256",
  "request_object_encryption_alg":"",
  "request_object_encryption_enc":"",
  "request_uris":[
    
  ],
  "client_id_issued_at":1723556609,
  "created_at":"2024-08-13T13:43:29.619067912Z",
  "updated_at":"2024-08-13T13:43:29.619067912Z",
  "client_secret_expires_at":0,
  "sector_identifier_uri":"https://keystore.directory.sandbox.threddid.com/99b2b599-8cc2-499e-b805-e3d84233ae8e/b9f04639-cdeb-425b-a310-450d3d293fd4/redirect_uris.json",
  "userinfo_signed_response_alg":"none",
  "id_token_signed_response_alg":"ES256",
  "id_token_encrypted_response_alg":"",
  "id_token_encrypted_response_enc":"",
  "tls_client_certificate_bound_access_tokens":true,
  "tls_client_auth_subject_dn":"",
  "tls_client_auth_san_dns":"",
  "tls_client_auth_san_uri":"",
  "tls_client_auth_san_ip":"",
  "tls_client_auth_san_email":"",
  "privacy":{
    "scopes":null
  },
  "subject_type":"pairwise",
  "backchannel_token_delivery_mode":"",
  "backchannel_client_notification_endpoint":"",
  "backchannel_authentication_request_signing_alg":"",
  "backchannel_user_code_parameter":false,
  "require_pushed_authorization_requests":false,
  "authorization_signed_response_alg":"ES256",
  "authorization_encrypted_response_alg":"",
  "authorization_encrypted_response_enc":"",
  "dpop_bound_access_tokens":false,
  "authorization_details_types":null,
  "post_logout_redirect_uris":[
    
  ],
  "app_url":"",
  "backchannel_logout_uri":"",
  "backchannel_logout_session_required":false,
  "client_secret":"xT4SDSlIp9J3aLMIHMtQ99Uok6onqaQJEiQ0Hp2QBXc",
  "hashed_secret":"c2dc89fd3581d6222a7a143f173a4696feee7773f4156ada52c241eea25b30990fb35f2faa42105f1e51895dd7ced75f0847659f6396fbc977cf71d73bef7a1a7f93830e871ae9fb767318b0c545ee9543dc8ae94044cfc8a9b26bcf8bad53e3ba00ef889d1d8338dfdbdedd1aed382b51a86cf5f08d21d4cbf6f23d66141c50",
  "software_id":"b9f04639-cdeb-425b-a310-450d3d293fd4",
  "software_version":"1.00",
  "software_statement":"eyJraWQiOiJzaWduZXIiLCJ0eXAiOiJKV1QiLCJhbGciOiJQUzI1NiJ9.eyJzb2Z0d2FyZV9zdGF0ZW1lbnRfcm9sZXMiOltdLCJvcmdfandrc190cmFuc3BvcnRfdXJpIjoiaHR0cHM6Ly9rZXlzdG9yZS5kaXJlY3Rvcnkuc2FuZGJveC50aHJlZGRpZC5jb20vOTliMmI1OTktOGNjMi00OTllLWI4MDUtZTNkODQyMzNhZThlL3RyYW5zcG9ydC5qd2tzIiwiYXBpX3dlYmhvb2tfdXJpcyI6W10sIm9yZ19zdGF0dXMiOiJBY3RpdmUiLCJsb2dvX3VyaSI6Imh0dHBzOi8vZXhhbXBsZS5jb20vbG9nby5wbmciLCJyb2xlcyI6W10sImlzcyI6InRocmVkZCBzYW5kYm94IFNTQSBpc3N1ZXIiLCJvcmdfandrc190cmFuc3BvcnRfaW5hY3RpdmVfdXJpIjoiaHR0cHM6Ly9rZXlzdG9yZS5kaXJlY3Rvcnkuc2FuZGJveC50aHJlZGRpZC5jb20vOTliMmI1OTktOGNjMi00OTllLWI4MDUtZTNkODQyMzNhZThlL2luYWN0aXZlL3RyYW5zcG9ydC5qd2tzIiwiY2xpZW50X2lkIjoiaHR0cHM6Ly9ycC5kaXJlY3Rvcnkuc2FuZGJveC50aHJlZGRpZC5jb20vb3BlbmlkX3JlbHlpbmdfcGFydHkvYjlmMDQ2MzktY2RlYi00MjViLWEzMTAtNDUwZDNkMjkzZmQ0IiwiY2xpZW50X2Rlc2NyaXB0aW9uIjoiVGVzdCBPcmcgNCBpcyBhIEN1c3RvbWVyIG9mIFRocmVkZCIsIm1vZGUiOiJMaXZlIiwic29mdHdhcmVfaWQiOiJiOWYwNDYzOS1jZGViLTQyNWItYTMxMC00NTBkM2QyOTNmZDQiLCJzb2Z0d2FyZV92ZXJzaW9uIjoiMS4wMCIsIm9yZ19uYW1lIjoiVGVzdCBPcmcgNCIsInNvZnR3YXJlX2ZsYWdzIjp7fSwib3JpZ2luX3VyaXMiOltdLCJjbGllbnRfbmFtZSI6IlRlc3QgT3JnIDQiLCJpYXQiOjE3MjM1NTYzNTAsImp3a3NfdHJhbnNwb3J0X3VyaSI6Imh0dHBzOi8va2V5c3RvcmUuZGlyZWN0b3J5LnNhbmRib3gudGhyZWRkaWQuY29tLzk5YjJiNTk5LThjYzItNDk5ZS1iODA1LWUzZDg0MjMzYWU4ZS9iOWYwNDYzOS1jZGViLTQyNWItYTMxMC00NTBkM2QyOTNmZDQvdHJhbnNwb3J0Lmp3a3MiLCJvcmdhbmlzYXRpb25fdGFncyI6W10sInN1YmplY3RfdHlwZSI6InBhaXJ3aXNlIiwicmVkaXJlY3RfdXJpcyI6WyJodHRwczovL2V4YW1wbGUuY29tL2NiIl0sInNlY3Rvcl9pZGVudGlmaWVyX3VyaSI6Imh0dHBzOi8va2V5c3RvcmUuZGlyZWN0b3J5LnNhbmRib3gudGhyZWRkaWQuY29tLzk5YjJiNTk5LThjYzItNDk5ZS1iODA1LWUzZDg0MjMzYWU4ZS9iOWYwNDYzOS1jZGViLTQyNWItYTMxMC00NTBkM2QyOTNmZDQvcmVkaXJlY3RfdXJpcy5qc29uIiwib3JnX2p3a3NfaW5hY3RpdmVfdXJpIjoiaHR0cHM6Ly9rZXlzdG9yZS5kaXJlY3Rvcnkuc2FuZGJveC50aHJlZGRpZC5jb20vOTliMmI1OTktOGNjMi00OTllLWI4MDUtZTNkODQyMzNhZThlL2luYWN0aXZlL2FwcGxpY2F0aW9uLmp3a3MiLCJvcmdhbmlzYXRpb25fZmxhZ3MiOnt9LCJqd2tzX3RyYW5zcG9ydF9pbmFjdGl2ZV91cmkiOiJodHRwczovL2tleXN0b3JlLmRpcmVjdG9yeS5zYW5kYm94LnRocmVkZGlkLmNvbS85OWIyYjU5OS04Y2MyLTQ5OWUtYjgwNS1lM2Q4NDIzM2FlOGUvYjlmMDQ2MzktY2RlYi00MjViLWEzMTAtNDUwZDNkMjkzZmQ0L2luYWN0aXZlL3RyYW5zcG9ydC5qd2tzIiwiZW52aXJvbm1lbnQiOiJTYW5kYm94Iiwib3JnX2lkIjoiOTliMmI1OTktOGNjMi00OTllLWI4MDUtZTNkODQyMzNhZThlIiwib3JnX2p3a3NfdXJpIjoiaHR0cHM6Ly9rZXlzdG9yZS5kaXJlY3Rvcnkuc2FuZGJveC50aHJlZGRpZC5jb20vOTliMmI1OTktOGNjMi00OTllLWI4MDUtZTNkODQyMzNhZThlL2FwcGxpY2F0aW9uLmp3a3MiLCJqd2tzX2luYWN0aXZlX3VyaSI6Imh0dHBzOi8va2V5c3RvcmUuZGlyZWN0b3J5LnNhbmRib3gudGhyZWRkaWQuY29tLzk5YjJiNTk5LThjYzItNDk5ZS1iODA1LWUzZDg0MjMzYWU4ZS9iOWYwNDYzOS1jZGViLTQyNWItYTMxMC00NTBkM2QyOTNmZDQvaW5hY3RpdmUvYXBwbGljYXRpb24uandrcyIsIm9yZ19udW1iZXIiOiIwMDAwMDAwNCIsImp3a3NfdXJpIjoiaHR0cHM6Ly9rZXlzdG9yZS5kaXJlY3Rvcnkuc2FuZGJveC50aHJlZGRpZC5jb20vOTliMmI1OTktOGNjMi00OTllLWI4MDUtZTNkODQyMzNhZThlL2I5ZjA0NjM5LWNkZWItNDI1Yi1hMzEwLTQ1MGQzZDI5M2ZkNC9hcHBsaWNhdGlvbi5qd2tzIiwic3RhdHVzIjoiQWN0aXZlIiwib3JnYW5pc2F0aW9uX2NvbXBldGVudF9hdXRob3JpdHlfY2xhaW1zIjpbXX0.N5wPwnVFcramX7BAYOWn_1tWcLxSRNaIxst-ZK_p29he5mN1_hdFF6BoVMG0Chh-dV_FL4-luQlg7Qn3EMRCb3RWp8U7pcj0lmFSDcUyvlQpoB5hqrXgjPEOkIC7uqJuTDjwakj0NFtJDtK_l_FVp-PA2ZsDJanwCxsnxxMxVFlxFPwCYk8jBTNE84zx092a4-Tj4VfE4e5S5HA7if8sR7PiXvAMWs1jBrUQ9enWacfu_Xno_-kywtrkAeR4fi-MGNeA4IkbYbh8LyhMjg3XXun87BoL8-b_An5fX5y-XS8VnENg3NFU3D8soQ05OKlXnIDT2Dp7v1lFlNYrV1jO9w",
  "dynamically_registered":true,
  "registration_access_token":"PKW64FAixrjhxewTH9lR26o7m6_GvbL6RKWv0x5mIM.dWPLOrdXw7yGu2R1HAWlx8dSr3Jf-thb_zNFEGSOUNg",
  "registration_client_uri":"https://auth.uat.threddid.com/confidential-clients/oauth2/register/https://rp.directory.sandbox.threddid.com/openid_relying_party/b9f04639-cdeb-425b-a310-450d3d293fd4",
  "registration_access_token_expires_in":0
}